package org.as3search {
	/*
	 * as3search - http://code.google.com/p/as3search
	 * Copyright (c) 2009-2010 by respective authors. All rights reserved.
	 *
	 * This library is free software; you can redistribute it and/or modify it under the
	 * terms of the GNU Lesser General Public License as published by the Free Software
	 * Foundation; either version 2.1 of the License, or (at your option) any later
	 * version.
	 *
	 * This library is distributed in the hope that it will be useful, but WITHOUT ANY
	 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
	 * PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
	 *
	 * You should have received a copy of the GNU Lesser General Public License along
	 * with this library; if not, write to the Free Software Foundation, Inc.,
	 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
	 */
	
	CONFIG::flex { import org.as3search.config.FlexSearchConfiguration; }
	import org.as3search.config.LightSearchConfiguration;
	import org.as3search.config.SearchConfiguration;
	import org.as3search.criteria.Criteria;

	/**
	 * <code>org.as3search.Search</code> provides a static, singleton approach 
	 * to accessing the search functionality provided by as3search. It wraps an
	 * org.as3search.config.SearchConfiguration instance and provides a facade
	 * for it. <br/><br/>
	 * 
	 * Depending on which version of as3search you included in your classpath,
	 * <code>configuration</code> is either set to an org.as3search.config.FlexSearchConfiguration
	 * or an org.as3search.config.LightSearchConfiguration.
	 * 
	 * @see org.as3search.config.SearchConfiguration
	 * @see org.as3search.config.FlexSearchConfiguration
	 * @see org.as3search.config.LightSearchConfiguration
	 */
	public class Search {
		
		private static var _configuration:SearchConfiguration = 
			new LightSearchConfiguration();
		
		CONFIG::flex {
			_configuration = new FlexSearchConfiguration();
		}
		/**
		 * Creates a new <code>Criteria</code> instance for searching through a 
		 * collection. The <code>Criteria</code> instance returned is created by
		 * the static configuration at <code>org.as3search.Search.configuration</code> using
		 * the <code>createCriteria()</code> method. 
		 * 
		 * @example The following example demonstrates how to search through a collection for 
		 * any items that have an id of 1:
		 * <listing version="3.0">
		 * var collection:Array = [{id: 0, username: "bob"}, {id: 1, username: "ted"}];
		 * var results:Array = Search.within(collection)
		 * 		.add(Restrictions.eq("id", 1))
		 * 		.list();
		 * </listing>
		 * 
		 * @param	value	The object to be searched. Typically, this is a collection type, 
		 * 		such as <code>Array</code> or <code>mx.collections.IList</code>, but it may
		 * 		be any object as well. If it cannot be determined to be a collection type, it is
		 * 		wrapped in a collection to enable <code>as3search</code> to use a consistent API.
		 * 
		 * @return A <code>Criteria</code> instance for searching through <code>value</code>. 
		 * 
		 * @see org.as3search.criteria.Criteria
		 * @see org.as3search.criteria.Restrictions
		 * @see org.as3search.config.SearchConfiguration
		 * @see org.as3search.providers.SearchProvider
		 */
		public static function within(value:Object):Criteria {
			return configuration.createCriteria(value);
		}
		/**
		 * The static <code>SearchConfiguration</code> instance to use with this singleton.
		 * By setting this property, <code>Search.within()</code> will use the <code>SearchConfiguration</code>
		 * that you pass to generate <code>Criteria</code> instances through the <code>createCriteria()</code>
		 * method. Thus, this property allows you to make <code>as3search</code> use a custom configuration
		 * for the static <code>Search</code> class.
		 * 
		 * @see org.as3search.config.SearchConfiguration
		 */
		public static function get configuration():SearchConfiguration { return _configuration; }
		public static function set configuration(value:SearchConfiguration):void { _configuration = value; }
	}
}